Skip to content

feat(extract): detect generated files by their content banner - #220

Merged
sunerpy merged 1 commit into
mainfrom
feat/tier4-generated-header
Aug 20, 2026
Merged

sunerpy merged 1 commit into
mainfrom
feat/tier4-generated-header

Conversation

@sunerpy

@sunerpy sunerpy commented Aug 20, 2026

Copy link
Copy Markdown
Owner

Tier 4 item 11 of the post-v1.5.0 upstream sync (#1500, plus the Wrangler double-by banner from 57e0854).

The defect

Go marks a generated file in its content, not its name. A payroll.go carrying // Code generated by protoc-gen-go. DO NOT EDIT. beside hand-written code was invisible to our path-only check:

before:  payroll.go and real.go rank by symbol count — the stub can win
after:   payroll.go generated=1     ← from the banner alone
         real.go    generated=0
         node    ComputePay -> real.go, payroll.go
         explore ComputePay -> real.go, payroll.go

The control that made the reproduction conclusive: renaming the same file to payroll.pb.go — content unchanged — already flipped the ranking, proving the demotion pipeline worked and only the signal was missing.

Conservative by construction

The flag only ever ADDS to the path signal. A file the path table already demotes stays demoted; a header scan can promote nothing. Precision comes from the patterns, not the generat stem pre-filter — the Go corpus pins a one-clause by line and a banner declared inside a function body as negatives, so a comment that merely discusses code generation is not a banner.

All three write paths, separately verified

codegraph-extract's engine returns an ExtractionResult and never builds a FileRecord — three independent sites do, each already holding &source:

path site
fresh index / index --force main.rs:4870
incremental sync sync.rs:760
outdated rebuild migrate.rs:130

All three call the same detect_generated_file(relative, &source). Filling a default at any one would make sync disagree with index --force and break the byte-equality invariant the whole golden suite rests on, so each has its own test. Zero hardcoded defaults remain in production code (the one at main.rs:6962 is inside #[cfg(test)]).

The version bump is load-bearing, proven across two binaries

direction result
old binary builds, new binary reads State: outdated (built with extraction version 8) → sync → 2 reindexed, 0 skipped, column added, flags 1/0
new binary builds, old binary reads State: future (built with extraction version 9) — fails closed, does not misread

0 skipped is the point: a DDL-only bump would have skipped both unchanged files and left them stuck at generated = 0 forever. SCHEMA_VERSION 7→8 carries the column, EXTRACTION_VERSION 8→9 forces re-extraction, STORAGE_PROTOCOL stays 2 because bumping it would make an old binary judge every phase future — a wider refusal than this warrants.

Golden movement, exactly as enumerated

artifact moved
files.json 16
schema.sql 17 (16 corpora + root)
colby.db 16
nodes.json / edges.json / refs.json 0

Zero movement in the extraction artifacts is the proof the flag never enters extraction output — any movement there would have meant a leak. A new reference/golden/go/ corpus pins the verdict itself: 3 ones and 3 zeros, the negatives being files that mention generation without a banner.

mini and godot additionally normalise their index CREATE order. That is expected and was predicted: they are migrated artifacts where the v7 migration appended idx_edges_identity, while newer corpora take it from the base schema in alphabetical position — sqlite_master order reflects CREATE order and compare_schema is a strict string comparison.

Verification

  • make ci green: 133 suites / 3408 passed / 0 failed (baseline 133 / 3371).
  • reference/golden/erlang/edges.json still holds its 2 legitimate recursive calls self-edges.
  • Hands-on QA on a real index for the banner verdict, the ranking on both node and explore, and both upgrade directions.

The plan cleared three review rounds. Round 1 found the design not implementable as written — the function it cited never built a FileRecord, and the missing piece would have silently broken sync/rebuild byte-equality. Round 2 found a criterion that ran the wrong code path (index instead of sync, which is what reaches migrate_project), a corpus count that was never counted, and three mutually inconsistent statements about mini.

Go's convention marks a generated file in its content, not its name, so a
`payroll.go` carrying `// Code generated by protoc-gen-go. DO NOT EDIT.` beside
hand-written code was invisible to a path-only check and could outrank the
implementation it shadows. The verdict is now decided at index time and stored on
the file row, so a query never reads a header to rank a result.

The flag only ever ADDS to the path signal: a file the path table already
demotes stays demoted, and a header scan can promote nothing. The window is
bounded, and precision comes from the patterns rather than the `generat` stem
pre-filter — a comment that merely discusses code generation is not a banner,
which the corpus pins with a one-clause `by` line and a banner declared inside a
function body as negatives.

All three extraction write paths compute it from the source they already read —
fresh index, incremental sync, and the outdated rebuild — because filling a
default at any one of them would make `sync` disagree with `index --force` and
break the byte-equality invariant the golden suite rests on. Each path has its
own test.

SCHEMA_VERSION 7 -> 8 carries the column. EXTRACTION_VERSION 8 -> 9 is what makes
an existing index classify outdated and re-extract; a DDL-only bump would leave
every old row stuck at zero forever, since sync skips unchanged files. Verified
in both directions across two binaries: the new one upgrades a v8 index with
`2 reindexed, 0 skipped`, and the old one refuses a v9 index as `future` rather
than misreading it. STORAGE_PROTOCOL stays 2 — bumping it would make an old
binary judge every phase future, a wider refusal than this warrants.

Sixteen corpora regenerate for the column plus a new go corpus; nodes, edges and
refs are byte-identical, because the flag never enters extraction output. mini
and godot additionally normalise their index CREATE order, which is expected:
they are migrated artifacts where the v7 migration appended an index the newer
corpora take from the base schema.
@codecov

codecov Bot commented Aug 20, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.79032% with 9 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
crates/codegraph-core/src/generated_header.rs 97.66% 8 Missing ⚠️
crates/codegraph-store/src/migrations.rs 98.64% 1 Missing ⚠️

Impacted file tree graph

@@            Coverage Diff             @@
##             main     #220      +/-   ##
==========================================
+ Coverage   95.28%   95.31%   +0.03%     
==========================================
  Files         140      141       +1     
  Lines       77287    78022     +735     
==========================================
+ Hits        73641    74367     +726     
- Misses       3646     3655       +9     
Files with missing lines Coverage Δ
crates/codegraph-cli/src/main.rs 90.86% <100.00%> (+<0.01%) ⬆️
crates/codegraph-core/src/types.rs 100.00% <100.00%> (ø)
crates/codegraph-mcp/src/engine.rs 97.70% <100.00%> (+0.09%) ⬆️
crates/codegraph-resolve/src/context.rs 98.47% <100.00%> (+<0.01%) ⬆️
crates/codegraph-resolve/src/resolver.rs 97.14% <100.00%> (+<0.01%) ⬆️
crates/codegraph-resolve/src/snapshot_context.rs 97.25% <100.00%> (+<0.01%) ⬆️
crates/codegraph-store/src/index_state.rs 83.33% <ø> (ø)
crates/codegraph-store/src/queries.rs 98.43% <100.00%> (+0.04%) ⬆️
crates/codegraph-watch/src/migrate.rs 76.14% <100.00%> (+0.22%) ⬆️
crates/codegraph-watch/src/sync.rs 97.91% <100.00%> (+0.08%) ⬆️
... and 2 more
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@sunerpy
sunerpy merged commit 9e75fed into main Aug 20, 2026
7 checks passed
@sunerpy
sunerpy deleted the feat/tier4-generated-header branch August 20, 2026 16:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant